Scripting documentation for ViRC 2.0 and later
----------------------------------------------

This file describes changes to the Versus language as documented in
versus.txt and ovs.txt.

The Versus language is based on ViRCScript, which was created by
Adrian Cable for Visual IRC '96. Among the differences are enhanced
support for objects, toolbars, lists and arrays. Also, instead of all
scripts running in the same environment, a separate interpreter is
created for each server, which affects object event handlers.

Last updated 13 Apr 2001 for 2.0pre6 - see changes.txt for later additions.

Variables
=========

$scripthost
  Contains "ViRC".
$ver
  Contains a description of the current version of the client, such as
  "ViRC 2.0".
$build
  Contains an integer describing the current version of the client, such
  as 200.
$prebuild
  Contains the current prerelease number, or 0 if this is a release version.
$N
  Contains the nick of the current server or DCC chat window. Undefined when
  the script is running on the global interpreter.
$server
  Describes the current server: either "global", "unconnected", or the
  server's name for itself.

Commands
========

Exit:
  Quits the client.

NewServerWindow:
  Creates a new server connection window.

ShowClientSetup:
  Displays the client configuration window.

ShowDCCList:
  Toggles display of the DCC list window.

ShowNotifySetup:
  Displays the notify list configuration window.

ShowServerList:
  Displays the server list window.

ShowScriptLog:
  Brings the script log window to the front, if ViRC was started with the
  -scriptlog parameter.

Connect:
  Causes the current server window to connect.

Disconnect:
  Causes the current server window to disconnect.

Server <server name>:
  Connects the current server window to another IRC server.
  <server name> may take the form of either 'irc.cris.com',
  'irc.cris.com:6665', or 'irc.cris.com:6665%password'. If a port is not given,
  the default is 6667.

  This command will attempt to match a server list entry by looking for an
  entry with the supplied server name, then the supplied host and port, and
  finally the supplied host and any port. For example, a server entry named
  "prison" with the hostname irc.prison.net and port 6670 can be matched by
  '/server prison', '/server irc.prison.net:6670', or just
  '/server irc.prison.net'. '/server prison:6667' will override the entry's port
  and connect to irc.prison.net on port 6667, but it will use all the other
  settings from the entry.

  If <server name> is prefixed by an asterisk, ViRC will not change the
  supplied hostname or port, and it will not match a server list entry by the
  server name. For example, '/server *prison' will connect to a host named
  "prison" on port 6667, even though the server entry named "prison" specifies
  a different host and port.

Quote <text>:
Raw <text>:
  Sends the text directly to the server. Quote and Raw are equivalent.

Msg <target> <text>:
  Sends the text to <target> as a private message. <target> may be an IRC
  nickname or channel name, or the name or number of a DCC chat preceded by
  an equal sign (e.g., '=myfriend'). If you want to send text to a channel,
  you should use Say instead.
  
  If you override Msg, your alias will be called for text entered in query
  and DCC chat windows.

Say [channel] <text>:
  Sends the text to <channel>. If <channel> is omitted, the text is sent to
  the currently active channel.

Notice <target> <text>:
  Sends the text to <target> as a private or channel notice. <target> may be
  an IRC nickname or channel name.

Quit [message]:
  Disconnects the current server window with a quit message. If <message> is
  omitted, a default message will be supplied.

TextOut [-nohilite] [> window] <color> <text>:
  Displays text in a window, using a specific color. If a right angle bracket
  follows the command name, the next word specifies the window (a channel
  name, query name, DCC chat name preceded by an equal sign, or '.' for the
  server window). If the bracket and window name are omitted, the text is
  displayed to the currently active window, or if the active window belongs
  to a different server, the text is displayed in the server notices window
  of the current server.
  
  If the -nohilite option is given and the target window is not active, the
  corresponding window tab will not be highlighted. Use this for messages that
  do not demand the user's attention.
  
  If <window> is specified but does not refer to an existing window, the text
  will not be displayed unless <window> is an appropriate name for a query
  window, in which case a query window will automatically be created.

  If <window> is a comma-separated list of window names, each one will be tried
  in order: query1,query2,#channel will first try query1, then query2, then
  #channel, and display in the first window that exists. If none of them exist,
  the text will not be shown unless the last name refers to a query window, in
  which case it will be created automatically.
  
  <window> can also be an object handle prefixed by a percent sign to display
  the text in a TRichEdit or TMonkeySex control that has been created with OVS.
  If the handle is invalid or does not refer to a control of the correct type,
  no text is displayed.
  
  If the text contains any \L characters (ASCII 10), the enclosed text will be
  displayed in ecHyperlink and underlined, and will act as a hyperlink when
  double-clicked: \Lwww2.foo.com\L. ViRC will add these automatically, so a
  script should only add \L when it knows that the client won't recognize the
  enclosed text as a link (but the client must be able to handle it as a link
  once it's clicked!). Double-clicking the link runs 'WebHyperlink <text>'; if
  WebHyperlink is an alias, it can use the $C variable to determine which 
  channel the link was in. Any other attribute codes inside \L will terminate
  the link.
  
  If the text contains any \S characters (ASCII 13), the enclosed text will be
  displayed in ecScriptLink and will run a command when clicked or double-
  clicked: \Schannel:#ViRC\S. Note that the text must contain a colon, and that
  the text before the colon determines which command will be run; the example
  will run a command called click_channel (the "channel:" will not be visible
  to the user). The command will receive the word 'single' or 'double' as its
  first parameter (depending on whether it was clicked once or twice), and the
  text after the colon as its remaining parameters. You can pass additional
  parameters at the beginning by putting spaces in the text:
  '\Schannel #ViRC:Click here to join #ViRC.\S' will run this when clicked:
    click_channel #ViRC single Click here to join #ViRC.
  This command can use $C to determine which channel the link was in. Any other
  attribute codes inside \S will terminate the link.

TextOutBitmap [-nohilite] [> window] <color> <bitmap> <text>:
  Displays text in a window, prefixed by a bitmap. <bitmap> can either be
  a filename (which must be all one word) or an integer returned by the
  $bitmap() function.

FlushBitmapCache:
  Empties the internal bitmap cache. Use this if a bitmap is changed after
  first being loaded and you want to display the new one.

FlushBitmapCache <filename>:
  Removes only the specified file from the bitmap cache.

CTCP <target> <text>:
  Sends the text to <target> as a CTCP (Client-To-Client Protocol) request.

RCTCP <target> <text>:
  Sends the text to <target> as a CTCP reply.

Ver <target>:
  Sends a CTCP version request to <target>. This is exactly equivalent to
  'CTCP <target> VERSION'.

Ping <target>:
  Sends a CTCP ping request to <target>. This is equivalent to
  'CTCP <target> PING $*mtime()'.

Mode <channel> <mode change>:
  Attempts to change the channel mode.

Umode <mode change>:
  Attempts to change your user mode. This is equivalent to
  'Mode $N <mode change>'.

Names <channel>:
  Retrieves a list of names of users on the channel.

Who <channel>:
  Retrieves a detailed list of users on the channel.

OnServer <id> <command>:
  Executes a command on another server. <id> is the index of the server's
  entry in $ServerList(), which is also the number that appears in the server
  window's title bar. If <id> is 0, the command will be executed on the
  global interpreter.

Load <filename> [parameters]:
  Loads a text file and executes it as script code. If the filename contains
  spaces, surround it with double quotes. The file will be passed

Topic [channel] [new topic]:
  Attempts to change the topic on a channel. If <channel> is omitted, the
  current channel will be used. If <new topic> is omitted, the current topic
  will be retrieved.

Kick [channel] <nick> [reason]:
  Attempts to kick someone from a channel. If <channel> is omitted, the
  current channel will be used. If <reason> is omitted, a default reason will
  be provided by the IRC server.

KB [channel] <nick> [reason]:
  Attempts to ban and kick someone from a channel. If <channel> is omitted,
  the current channel will be used. If <reason> is omitted, a default reason
  will be provided by the IRC server.

Ban [channel] <nick>:
  Attempts to ban someone from a channel. If <channel> is omitted, the current
  channel will be used.

Part [channel]:
  Leaves the channel. If <channel> is omitted, leaves the current channel.

Query <nick> [message]:
  Creates a new query window for <nick>. If <message> is specified, it will be
  sent (via 'Msg <nick> <message>') as soon as the window is created.

AddToIAL <nick> <address>:
  Adds the given nick and address to ViRC's IAL (Internal Address List), for
  use with $getaddress().

RemoveFromIAL <nick>:
  Removes the given nick from the IAL.

Me [channel] <text>:
  Sends the text to the channel as a CTCP ACTION. If <channel> is omitted, the
  action is sent to the currently active channel.

Desc <target> <text>:
  Sends the text to <target> (a channel, nickname, or DCC chat name preceded
  by an equal sign) as a CTCP ACTION. If you want to send an action to a
  channel, you should use Me instead.
  
  If you override Desc, your alias will be called when /me is used in a query
  or DCC chat window.

MenuHint <name> on <tree> = <text>:
  Sets a hint for a menu item. The hint will be displayed in the status bar of
  the main ViRC window while the menu item is highlighted.

DCC Send <nick> [filename]:
  Sends the file to <nick> using the DCC protocol. If <filename> is omitted, a
  standard file dialog box will appear and allow the user to choose a file.
  
  If the other person is using a client that supports it, you should use TDCC
  instead.

DCC TSend <nick> [filename]:
TDCC Send <nick> [filename]:
  Sends the file to <nick> using the Turbo DCC protocol. If <filename> is
  omitted, a standard file dialog box will appear and allow the user to choose
  a file. DCC TSend and TDCC Send are equivalent.

  Turbo DCC is not supported by all clients. However, it is supported by BIRC,
  PIRCH, XiRCON, and BitchX.

DCC Accept [filename]:
  When used in an <OnDCCRequest> event, automatically accepts the request. If
  the request is a file transfer and <filename> is specified, the file will be
  saved with that name. If the file already exists, it will be overwritten.

DCC Reject:
  When used in an <OnDCCRequest> event, automatically cancels the request.

DCC Resume <offset> [filename]:
  When used in an <OnDCCRequest> event, automatically accepts the request. If
  the request is a file transfer and <filename> is specified, the file will be
  saved with that name. If the file already exists, the transfer will be
  resumed from the specified offset.

DCC Request <type> <nick> <user@host> <params>:
  Adds a DCC request to the DCC list window and runs the <OnDCCRequest> event
  for it. <type> can be either CHAT, SEND, or TSEND. If <type> is CHAT,
  <params> is two words: the IP address and the port. If <type> is SEND or
  TSEND, <params> is four words: the filename, IP address, port, and file
  size. If the filename contains spaces, it should be surrounded by double
  quotes. If <type> is SEND (but not TSEND), the file size is optional.

Min <window>:
Max <window>:
Restore <window>:
Close <window>:
Show <window>:
Hide <window>:
  Minimizes, maximizes, restores, closes, shows, or hides the window.
  <window> can also be !Main to operate on the main ViRC window, except for
  Show and Hide. Note that when you click the window's minimize button, the
  window is actually hidden, not minimized.

SetInputLine <window> <text>:
  Sets the contents of <window>'s input line.

Clear [window]:
  Clears the output display of the given window. If <window> is omitted,
  the current window's output will be cleared.

WebHyperlink <URL>:
  Opens the URL using your default web browser.

Notify [nicks]:
  Modifies the notify list. <nicks> is a space-separated list of nicks. Each
  nick is added to the list, or removed if it is prefixed with a minus sign.
  For example, 'Notify foo -bar -baz' would add foo, remove bar, and remove
  baz. If <nicks> is omitted, the current notify list is shown.

FireEvent [-one] <name> [args]:
  Runs the event with the given name, using <args> as parameters. Only events
  whose masks match <args> will run. The first word of <args> will be passed
  in as $0, and so on. <name> may contain wildcards, in which case all the
  events with matching names and masks will be fired. If the -one option is
  given, only the most specific matching event will be fired.

FireMenuItem [> channel] <item> on <tree> [= parameters]:
  Runs the specified menu item handler. If the angle bracket and <channel> are
  specified, $C will be set to <channel>; otherwise, it will be set to the
  active window's name. If the equal sign and <parameters> are specified, the
  menu item will receive <parameters> as $1-. $0 will be set to the item's
  name prefixed with a '!'.

SetUserField <nick!user@host> <fieldname> <data>:
  Associates the string <data> with the given user mask and field. <fieldname>
  can be any word, but you should limit the number of different fields to
  save space.

DelUserField <nick!user@host> <fieldname>:
  Deletes the user list entry for the given user mask and field. Only the
  specific entry for this mask will be removed; using DelUserField with the
  mask '*!*@*.foo.com' will not remove an entry for '*!user@ppp*.foo.com'.

Log Open <window>:
  Begins logging in the named window.

Log Close <window>:
  Ends logging in the named window.

DNS <hostname/ip/nickname>:
  Consults your nameserver to translate a hostname to an IP address or vice
  versa, then displays the results. This will block script execution while
  waiting for the DNS reply, but won't freeze the client.
  
  If the parameter contains no dots and doesn't start with a number, it
  will be treated as a nickname, and looked up with $getaddress(). To
  prevent this, prefix the hostname with a *: /dns *localhost

Cycle <channel>:
  Leaves and rejoins a channel without closing its window.

Asay <text>:
  Says the text to every channel on the current server.

Ame <text>:
  Sends the text as an action to every channel on the current server.

SimulateServerData <text>:
  Fires internal and user-defined events as if <text> had just arrived from
  the server. The events are fired immediately, even if there is unprocessed
  text in the actual server socket buffer.

Kill <nick> <reason>:
  Boots <nick> off the IRC network if you are an IRC operator.

Away [reason]:
  Marks you as away for the given reason; this text will appear in your
  /whois listing and when someone sends you a private message. If <reason>
  is omitted, you will no longer be marked as away.

UnEvent <name>:
  Deletes the event with the given name, if one exists.

SetServData <server name> <text>:
  Sets the 'scriptdata' field of a server entry.

SetNetData <network name> <text>:
  Sets the 'scriptdata' field of a network entry. <network name> must be
  quoted as a list entry, since it can contain spaces or be an empty string
  (for the 'no network' entry).

AddScriptControl <area> <type> <caption> <name> [options]:
  Creates a new control in either the client setup window or the server list
  for scripts to easily maintain their settings. The value of the control can
  be changed by the user and the changes will automatically be saved.

  <area> determines where the control appears and how the values are stored. It
  can be either "config" (to appear in client setup), "network" (to appear on
  the network page of the server list), or "server" (to appear on the server
  page of the server list). "config" controls are saved as a client-wide
  setting and can be manipulated with SetSetting and $getsetting(); "network"
  and "server" controls are saved with each network or server and can be
  manipulated with SetNetSetting/$getnetsetting() and SetServSetting/
  $getservsetting().

  <type> determines what kind of control appears. Possible values are "edit",
  "check", "radio", and "button". Note that "button" controls simply run a
  command; there is no data in the control for the user to edit. A button could
  be used to bring up an OVS dialog box with more settings, for example.

  <caption> is the string that will be displayed on the control (for a check
  box or button) or as a label next to the control (for an edit box or radio
  buttons). It should be quoted as a list item.

  <name> is the name of the field used to manipulate the control's value in
  $getsetting() and so on, unless the control is a button, in which case it is
  the name of the command used to implement the button. The command will be
  called with $1 as "click" when the button is clicked. The client will also
  call it as a function with $1 as "display" when it wishes to retrieve a
  string that will appear to the right of the button (when the form containing
  the button is shown, and after the button is clicked); return a string in
  $fresult, or return an empty string if none is appropriate.

  The interpretation of <options> depends on the control type. For radio
  buttons, <options> should be a list of strings (each quoted as list items)
  that will be used as captions of the radio buttons. One button will be
  created for each string in this list, and the value of the control will be a
  number from 0 to one less than the number of buttons. For edit boxes,
  <options> can be "password" if the characters typed in the box should appear
  onscreen as asterisks. For check boxes, <options> can be "transparent" if the
  user should be allowed to set it to greyed, rather than all the way checked
  or unchecked (in which case the value will be 2). <options> has no meaning
  for buttons.

DLL <filename> <function> [data]:
  Loads the DLL specified by <filename>, and calls <function> with the
  parameter <data>. If <data> is omitted, an empty string is passed. The
  calling conventions are described in vircdll.txt.

Exec <filename> [parameters]:
  Executes the file, optionally passing a parameter string. This is just like
  typing the filename and parameters into the Run dialog box - it will open
  a program, document, or URL.

Timer [name] <seconds> <repeats> <command>:
  Creates a new timer called <name>, waiting <seconds> seconds, repeating
  <repeats> times, and running <command>. If <name> is omitted, a unique name
  will be generated. If <repeats> is 0, the timer repeats forever. <command>
  will not be evaluated before it is run; if it should be, prefix it with Eval.
  
  Timer names are shared across all servers, and must not start with a digit.
  If a timer called <name> already exists, it will be deleted first.

MTimer [name] <millisecs> <repeats> <command>:
  Same as Timer, but the delay is given in milliseconds (1/1000 second) instead
  of seconds.

Timers:
Timers all:
  Displays a list of all timers running on the current server, or on all
  servers if 'timers all' is used.

UnTimer <name>:
  Deletes the timer called <name>.

Functions
=========

$NewServerWindow():
  Creates a new server window and returns its ID for use with OnServer.

$StrTrim(<text>):
  Returns <text> after removing a leading colon (if present), then removing
  any leading or trailing control-A characters.

$NickTrim(<text>):
  Returns <text> after removing any leading nickname flags (@, %, or +).

$IsChannel(<text>):
  Returns 1 if <text> could be the name of a channel, or 0 if not. ViRC
  considers any string beginning with a # or & to be a legal channel name.

$NickList(<channel>):
  Returns a list of all the nicknames on <channel>, or the null string if you
  aren't on that channel.

$OpList(<channel>):
  The same as $NickList(), but only returns the names of channel operators
  (which are flagged with an @ in the channel window's nick list).

$VoiceList(<channel>):
  The same as $NickList(), but only returns the names of channel voices
  (which are flagged with a + in the channel window's nick list).

$HalfOpList(<channel>):
  The same as $NickList(), but only returns the names of channel half-ops
  (which are flagged with a % in the channel window's nick list).

$PeonList(<channel>):
  The same as $NickList(), but only returns the names of peons (users who are
  not ops, voices, or half-ops).

$IsOn(<nick> <channel>):
  Returns 1 if <nick> appears in $NickList(<channel>), or 0 if not.

$IsOp(<nick> <channel>):
  Returns 1 if <nick> appears in $OpList(<channel>), or 0 if not.

$IsVoice(<nick> <channel>):
  Returns 1 if <nick> appears in $VoiceList(<channel>), or 0 if not.

$IsHalfOp(<nick> <channel>):
  Returns 1 if <nick> appears in $HalfOpList(<channel>), or 0 if not.

$GetMode(<channel>):
  Returns the mode string for <channel>, or an empty string if the channel
  is not open. This string includes parameters, such as "+stl 15".

$GetTopic(<channel>):
  Returns the topic string for <channel>, or an empty string if the channel
  is not open.

$GetKey(<channel>):
  Returns the key for <channel>, or an empty string if the channel is not
  open or does not have mode +k set.

$GetLimit(<channel>):
  Returns the user limit for <channel>, or 0 if the channel is not open or
  does not have mode +l set.

$GetWindowId(<window>):
  Returns a number that uniquely identifies the specified window. These
  numbers are unique among all server windows for the client, all DCC chat
  windows for the client, and all channels and query windows for the current
  server window. For server windows and DCC chats, this number appears in the
  title bar. For other window types, this number is not visible to the user.

$ChannelList():
  Returns a list of all the channel windows for the current server.

$ServerList():
  Returns a list of all the server windows. The index of each item in this
  list is the number that appears in the server window's title bar and is
  returned by $GetWindowId(). The first element is "global", and any spaces
  between server windows are "destroyed".

  For example: Suppose you create a server window and do not connect it. Then
  you create another and connect it to irc.concentric.net. $ServerList() will
  return "global unconnected irc.concentric.net:6667". Now suppose you close
  the first server window, leaving the second one connected. $ServerList()
  will return "global destroyed irc.concentric.net:6667".

$CurrentServer():
  Returns the index of the current server in the list returned by
  $ServerList(), or 0 if the function is called from the global interpreter.

$IsQuerying(<nick>):
  Returns 1 if there is a query window open for <nick> on the current server,
  or 0 if not.

$QueryList():
  Returns a list of all the query windows for the current server.

$IsDCCChatting(<nick>):
  Returns 1 if there is a DCC chat window open for <nick>, or 0 if not.

$DCCChatList():
  Returns a list of all the DCC chat windows open on all server windows (since
  DCC chat works independently of the server).

$DCCChatNick(<id>):
  Returns the nick on the other end of the specified DCC chat, or the empty
  string if there is no such DCC chat. <id> can be a number, a nick, or a
  window name.

$GetAddress(<nick>):
  Returns the address (user@host) of <nick>, or 'unknown@unknown' if there is
  no such nick on IRC. This function will read the address out of the IAL if
  it has been added with AddToIAL.

$IsInIAL(<nick>):
  Returns 1 if <nick> is in the current server's IAL, or 0 if not.

$EncodeIP(<dotted ip>):
  Returns <dotted ip> converted into an integer in network byte order. This is
  useful for sending DCC requests.

$DecodeIP(<numeric ip>):
  Returns <numeric ip> converted into a dotted IP address. This is useful for
  displaying an incoming DCC request.

$AliasList():
  Returns a list containing the name of every alias that has been added. This
  can also be retrieved with the GetAliasList method of TStringList.

$EventList():
  Returns a list containing the name of every event that has been added. This
  can also be retrieved with the GetEventList method of TStringList.

$EventMask(<event name>):
  Returns the given event's activation mask.

$EventExists(<event name>):
  Returns 1 if the event exists, or 0 if not.

$GetMenuHint(<name> on <tree>):
  Returns the given menu item's hint message.

$mIRCColor(<num>):
  Returns the RGB value of the mIRC color specified by <num>, or 0 if the
  number is out of the range 0..15.

$ActiveWindow():
  Returns the window name of the currently active child window, or . if there
  is no active child window or the active window belongs to another server.

$ActiveServer():
  Returns the server ID number of the server that owns the active child
  window, or 0 if there is no active child window or the active child is a
  DCC chat window.

$Bitmap(<filename>):
  Loads a .bmp image into the internal cache and returns a unique integer.
  If the file has already been loaded, the same integer will be returned,
  unless FlushBitmapCache has been called in the meantime.

$UhostToMask(<user@host>):
  Generates a ban mask that matches the given user@host, of the form
  *!*user@*host.

$NickToMask(<nick>):
  Looks up the nick's address using $GetAddress(), then generates a matching
  ban mask. If the nick's address cannot be found, a mask of the form
  nick!*@* is returned. 

$Notify():
  Returns the current notify list as a space-separated list of nicks.

$Notify(<nick>):
  Returns 1 if the nick is in the notify list and currently signed on (as far
  as ViRC knows), or 0 otherwise.

$TimeConnected():
  Returns the number of seconds the current server window has been connected,
  or 0 if the server is unconnected.

$GetSetting([path] <name>):
  Reads a setting from ViRC's registry key. If <path> is specified, it is a
  space-separated list of keys to traverse: for example,
  $GetSetting(Notify Interval).

  ViRC saves its settings in:
    HKEY_CURRENT_USER\Software\MeGALiTH Software\Visual IRC 2.

$GetUserField(<nick!user@host> <fieldname>):
  Retrieves the string that has been associated with the given user and field,
  or an empty string if no entry can be found. The most specific matching
  entry that exists for that field will be used: for example, calling this
  function for joe!user@ppp5.foo.com might return the string associated with
  *!user@ppp*.foo.com.

$UserFieldList([fieldname]):
  If <fieldname> is omitted, returns a list containing every field in the user
  list; otherwise, returns a list containing every nick!user@host mask with
  an entry in the given field. 

$IdleTime():
  Returns the number of seconds that have passed since data was last sent to
  the server.

$ServerHost():
  Returns the hostname:port used to connect to the server, or an empty string
  if there is no server connection.

$GetPath():
  Returns the path where the ViRC executable is located, including the
  trailing backslash.

$IsLogging(<window>):
  Returns true if the named window is currently logging.

$DNS(<hostname/ip/nickname>):
  Consults your nameserver to translate a hostname to an IP address or vice
  versa, then returns the results (or an empty string if the attempt failed).
  This will block script execution while waiting for the DNS reply but not
  freeze the client.

  If the parameter contains no dots and doesn't start with a number, it
  will be treated as a nickname, and looked up with $getaddress(). To
  prevent this, prefix the hostname with a *: $dns(*localhost)

$IsIP(<text>):
  Returns true if <text> is a valid numeric IP address. Note that strings like
  '5' and '127.1' are valid IP addresses.

$SelectServer():
  Displays the server list window so the user can choose a server entry by
  double-clicking it, or selecting it and pushing OK. The return value is the
  selected entry's server name, or an empty string if the user cancels.

$SelectNetwork():
  Displays the server list window so the user can choose a network entry. The
  return value is the selected entry's network name, or an empty string if the
  user cancels or selects 'no network'.

$ServerID():
  Returns the server name of the server entry currently being used, or an
  empty string if there is none.

$NetworkID():
  Returns the name of the network entry currently being used, or an empty
  string if there is none.

$GetServSetting([server name] <setting name>):
  Looks up a setting using the server entry, network entry, and global
  configuration. If <server name> is supplied, the entry by that name will be
  used instead of the currently active entry. Boolean settings are returned
  as either 0 or 1. The available settings are:
    nicklength (int), modeargs (int), defnicks (str), ident (str),
    realname (str), atchan (bool), multinicks (bool), hostname (str),
    network (str), password (str), scriptdata (str).
  'defnicks' returns a list of nicks, in order: server-specific nicks,
  network-specific nicks, and global default nicks. Each nick is quoted as a
  list item. 'network' returns the name of the network associated with the
  server.
  An empty string will be returned if the setting is invalid, or if a server
  name is given but no entry exists by that name.

$GetNetSetting([network name] <setting name>):
  Looks up a setting using the network entry and global configuration. If
  <network name> is supplied, the entry by that name will be used instead of
  the currently active entry. Return values and available settings are the
  same as above, except that 'defnicks' only returns network-specific and
  global nicks, and these settings are not available: hostname, network,
  password.

$PasswordQuery(<text>):
  Shows a dialog box requesting a password from the user. This works just
  like the $?= pseudo-function, but the password is masked with asterisks as
  it is entered. If <text> contains a vertical bar, the text to the right of
  it will be used as the default value (which is returned if the user
  cancels): $passwordquery(Enter your password:|shazam)

$GetInputLine(<window>):
  Returns the contents of <window>'s input line.

$StripAttrs(<text>):
  Removes attribute codes (bold, italic, color, etc.) from <text> and returns
  the plain text. 

$StripLinks(<text>):
  Removes hyperlinks (\Lfoo\L) and script links (\Scmd:foo\S), leaving
  attribute codes alone.

$DLL(<filename> <function> [data]):
  Loads the DLL specified by <filename>, calls <function> with the
  parameter <data>, and returns the result. If <data> is omitted, an empty
  string is passed. The calling conventions are described in vircdll.txt. If
  the DLL function does not return a value, $DLL() returns an empty string.

$Timer([name] <seconds> <repeats> <command>):
  Creates a new timer called <name>, waiting <seconds> seconds, repeating
  <repeats> times, and running <command>. If <name> is omitted, a unique name
  will be generated. Returns the name of the new timer.
  
  If <repeats> is 0, the timer repeats forever. <command> will not be
  evaluated before it is run; if it should be, prefix it with Eval.
  
  Timer names are shared across all servers, and must not start with a digit.
  If a timer called <name> already exists, it will be deleted first.

$MTimer([name] <millisecs> <repeats> <command>):
  Same as $Timer(), but the delay is given in milliseconds (1/1000 second)
  instead of seconds.

$TimerExists(<name>):
  Returns true if a timer called <name> exists.

$TimerList([serverid]):
  Returns a list of all timers running on the identified server, or on all
  servers if <serverid> is omitted.

$GetTimer(<name>):
  Returns a string of the form "interval repeats command", where interval is
  given in milliseconds and repeats is the number of times the timer will be
  called again. Returns an empty string if no timer called <name> exists.

$LocalNick(=<ID>):
  Returns your nickname on the specified DCC chat connection.

$RemoteNick(=<ID>):
  Returns the remote user's nickname on the specified DCC chat connection.

Menu Trees
==========

ViRC's menu trees are MT_MAINMENU, MT_SERVERPOPUP, MT_NOTIFYPOPUP,
MT_CHANNELTEXTPOPUP, MT_CHANNELNICKSPOPUP, MT_QUERYPOPUP, and MT_CHATPOPUP.
Each menu tree should be zero or more lines of the form:
  <id> <hotkey> <magic> <depth> <name>
where <id> is a one-word identifier unique to this menu tree, <hotkey> is a
string of the form "Alt+X" (or "<none>" for no hotkey), <magic> is a number
describing the special behavior of this item, <depth> is how far this item is
indented (0 for a top-level item), and <name> is the caption of the menu item
(where an ampersand makes the next letter underlined, and && displays a single
ampersand).

For MT_SERVERPOPUP, <magic> can take the following values:
  0 - item is always enabled
  1 - enabled when connected to the server
  2 - disabled when connected to the server
  3 - item is always disabled
For MT_CHANNELTEXTPOPUP and MT_CHANNELNICKSPOPUP, it can take these values:
  0 - item is always enabled
  1 - enabled when opped on the channel
  2 - disabled when opped on the channel
  3 - item is always disabled
Currently, for the other trees <magic> is ignored and the item is always
enabled.

To assign code to a menu item, use the MenuItem block:
  MenuItem M_CTCPVERSION on MT_CHANNELNICKSPOPUP
    foreach ($i; $listfromwords($1-))
      CTCP $i VERSION
    endforeach
  EndMenuItem
To assign code that is run when you double-click in the area, use the special
item ID "<DoubleClick>".

Menu item handlers run on the appropriate interpreter (the global interpreter
for MT_MAINMENU and MT_CHATPOPUP, and the server window's interpreter for all
others), and receive the following parameters and variables:
  MT_MAINMENU, MT_SERVERPOPUP - none.
  MT_NOTIFYPOPUP - all selected nicks in $1-, focused nick in $nick.
  MT_CHANNELTEXTPOPUP - channel name in $C.
  MT_CHANNELNICKSPOPUP - all selected nicks in $1-, focused nick in $nick,
                         channel name in $C.
  MT_QUERYPOPUP - nick of query target in $1, $nick, and $C.
  MT_CHATPOPUP - nick of DCC chat target in $1 and $nick, window name in $C.

Note that even though $1- might look like a list, it isn't a real list. The
elements might contain unquoted backslashes, which will cause list functions
and ForEach loops to give incorrect results. Use $listfromwords($1-) if you
need to access $1- like a list.

Events
======

Define an event using the syntax:
  Event MyEventName "<event mask here>"
    <code>
  EndEvent
where MyEventName is a unique name for the event, and <event mask here> is a
standard VSInterp wildcard mask (using %, *, ?, and ¬). The event mask is
evaluated before it's added, which lets you use variables and backslash escapes
in the mask.

ViRC matches the event masks against text from the server (after removing any
trailing newlines and CTCP delimiters) and fires the most specific event that
matches. Each event is assigned a priority when it's created, which ViRC uses
to compare the specificness of events. Each *, or ¬ in the mask earns it zero
priority points, each % earns it one point, each ? earns it two points, and
each other character (or escaped wildcard) earns it three points. The mask with
the highest priority value is considered the most specific.

The word-break wildcard (¬, alt-0172) is useful for matching CTCP messages.
Since ViRC automatically removes trailing CTCP delimiters (\A), this mask will
match any CTCP VERSION request, but not CTCP VERSIONFOO:
  % PRIVMSG % :\AVERSION¬

To run a specific event *in addition to* the less specific events, rather than
*instead of* them, use the FallThrough command:
  Event AnyCTCP "% PRIVMSG % :\A*"
    TextOut > . ecCTCP *** CTCP $strtrim($3) from $nick
  EndEvent
  Event CTCPVERSION "% PRIVMSG % :\AVERSION¬"
    ^RCTCP $nick VERSION I am proudly running $ver.
    FallThrough
  EndEvent

Script Hooks Called by ViRC
===========================

ViRC calls these script-defined events:
  <OnStart*            called when ViRC starts.
  <OnClose*            called just before ViRC exits.
  <OnConnect*          called when the IRC server acknowledges the connect (in
                       the 004 numeric). note that this is not fired
                       immediately after the socket connects.
  <OnDisconnect*       called when the IRC socket is closed.
  <OnSocketOpen*       called as soon as the IRC socket connects, before any
                       NICK or USER command is sent.
  <OnCreateWindow*     called when a new ViRC form is created. $0 is the form
                       type (TServerForm, TChannelForm, TDCCChatForm, or
                       TQueryForm) and $1 is the window name. if the form is a
                       DCC chat form, $1 contains the non-unique name (=nick)
                       and $2 contains the unique name (=123).
  <OnNewDCCChatText*   called when new text comes in on a DCC chat connection
                       (ViRC doesn't display the text by itself). $0 is the
                       nick, $1 is the window name, $2- is the text. only the
                       most specific matching event will be run, unless
                       FallThrough is used.
  <OnDCCChatClosed*    called when the remote end closes a DCC chat
                       connection. $0 is the nick and $1 is the window name.
  <OnDCCRequest*       called when a new DCC request is added to the list
                       (using the DCC Request command). see below.
  <OnUserSetupOK*      called when the user clicks the OK button to close the
                       client setup window and save changes.
  <OnUserSetupCancel*  called when the user clicks the Cancel button to close
                       the client setup window and discard changes.
  <OnErrorConnecting*  called when a socket error occurs before the socket is
                       connected. $0 is the error number and $1- is the
                       message.
  <OnMyChanText*       called by the built-in /say command to display text
                       that the user types into a channel. $0 and $C are the
                       channel, $1- is the text.
  <OnMyPrivMsg*        called by the built-in /msg command to display text
                       sent as a private message (other than in a query). $C
                       is the active window, $0 is the target nick, and
                       $1- is the text.
  <OnMyNotice*         called by the built-in /notice command to display text
                       sent as a notice. $C is the active window, $0 is the
                       target nick or channel, and $1- is the text.
  <OnMyCTCP*           called by the built-in /ctcp command to display CTCP
                       requests sent by the user. $C is the active window, $0
                       is the target nick or channel, and $1- is the text.
  <OnMyRCTCP*          called by the built-in /rctcp command to display CTCP
                       replies sent by the user. $C is the active window, $0
                       is the target nick or chanel, and $1- is the text.
  <OnMyChanAction*     called by the built-in /me command to display actions
                       the user performs in a channel. $C and $0 are the
                       channel, $1- is the text.
  <OnMyPrivAction*     called by the built-in /desc command to display
                       actions sent privately to another user. $C is the
                       active window, $0 is the target nick, and $1- is the
                       text.
  <OnMyQueryText*      called by the built-in /msg command to display text
                       that the user types into a query or DCC chat. $C and $0
                       are the window name (nick or =number), $1- is the text.
                       $N is set to the appropriate local nickname when called
                       for a DCC chat.
  <OnMyQueryAction*    called by the built-in /desc command to display actions
                       the user performs in a query. $C and $0 are the window
                       name, $1- is the text. $N is set to the appropriate
                       local nickname when called for a DCC chat.

All of these are called using wildcards, which means that <OnStart>,
<OnStart_MyScript>, and <OnStartFoo> will all be called. Events with names
surrounded by angle brackets will never be matched against text from the IRC
server.

Event masks are still matched when calling hooks. This event:
  Event <OnCreateWindow_Servers> "TServerForm *"
    <code>
  EndEvent
will only run when a server form is created. However, with the exception of
<OnNewDCCChatText*, all matching events will be called (not just the most specific one).

ViRC will also call user-defined aliases:
  WEBHYPERLINK <url>         called when you double-click on a hyperlink.
  CONNECT                    called when you click the server's connect button.
  DISCONNECT                 called when you click the server's disconnect
                             button.
  SAY <channel> <text>       called when you type text in a channel, and by
                             /asay.
  ME <channel> <text>        called by /ame.
  MSG <nick> <text>          called when you type text in a query, and by
                             /query <nick> <text>.
  MSG =<id> <text>           called when you type text in a DCC chat window.
  DESC <nick> <text>         called when you use /me in a query.
  DESC =<id> <text>          called when you use /me in a DCC chat window.
  CTCP <nick> <text>         called by /ver and /ping.
  QUIT <text>                called by /server when you're already connected.
  PART <channel>             called when you close a channel window.
  MODE <channel> <text>      called by /ban and /kb.
  KICK <channel> <nick> <text>    called by /kb.
  $NickToMask(<nick>)        called by /ban and /kb.

Writing an <OnDCCRequest> Event
===============================

The <OnDCCRequest> event is fired by the DCC Request command after the request
is added to the DCC list. $nick, $user, and $host describe the nick and
user@host that were passed in the DCC Request command. The other parameters
are the type in $1 (CHAT, SEND, or TSEND), the encoded IP in $2, the remote
port in $3, the file size in $4 (or 0 if the size is unknown), and the filename
in $5-.

The event can run three special commands to automatically deal with the
request:
  DCC Reject                          aborts the transfer immediately.
  DCC Accept [<filename>]             accepts the transfer immediately,
                                      optionally renaming it.
  DCC Resume <size> [<filename>]      resumes the transfer immediately,
                                      optionally renaming it. <size> is the
                                      position to start resuming from, where
                                      0 is the beginning of the file.

If the event doesn't run any of these commands, the request will stay in the
DCC list as usual.

Mappable Objects
================

For the form name in a $MapObject(form name[:control name]) call, you can use
a window name, or one of the special values: 

  !Main - main ViRC form
  !UserSetup - configuration window
  !About - about box
  !DCCList - dcc list window
  !Notify - notify setup window
  !ScriptEditor - script editor

ViRC automatically adds the main form itself with object
handle 0. The mappable controls for each window type are:

Server windows (TServerForm)
----------------------------

ConnectBtn, DisconnectBtn (TToolbarButton97) - the buttons to connect to and
   disconnect from the server.
ServerTxt (TEdit97) - the edit control containing the server name. 
IALTimer (TTimer) - the timer that runs every minute to clean out the IAL.
NotifyTimer (TTimer) - the timer that sends ISON commands for the notify list.
ServerPopup, NotifyPopup (TPopupMenu) - the popup menus.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMemo) - the box where text is entered.
Notify (TListBox) - the notify nicks list.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
   toolbars can be placed.
ServerToolbar (TToolbar97) - the toolbar containing ConnectBtn and
   DisconnectBtn.
ServerSelectionToolbar (TToolbar97) - the toolbar containing ServerTxt.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
   tab bar.

Channel windows (TChannelForm)
------------------------------

ChannelTextPopup, ChannelNicksPopup (TPopupMenu) - the popup menus.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMemo) - the box where text is entered.
NickList (TListBox) - the channel nicks list.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
   toolbars can be placed.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
   tab bar.

Query windows (TQueryForm)
--------------------------

QueryPopup (TPopupMenu) - the popup menu.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMenu) - the box where text is entered.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
   toolbars can be placed.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
   tab bar.

DCC Chat windows (TDCCChatForm)
-------------------------------

ChatPopup (TPopupMenu) - the popup menu.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMenu) - the box where text is entered.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
   toolbars can be placed.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
   tab bar.

Main form (TMainForm)
---------------------

MainMenu (TMainMenu) - the main menu.
StatusBar (TStatusBar) - the status bar. set the SimpleText property to change
   the displayed text.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
   toolbars can be placed.

Client setup form (TConfigForm)
-------------------------------

Use BCONV to get the code for this form.

Notify setup form (TNotifyForm)
-------------------------------

AddBtn, RemoveBtn (TButton) - the buttons to add or remove nicks.
NickList (TListBox) - a list box containing the nicks.
AutoNotify (TCheckBox) - the check box to enable automatic notify monitoring.
NotifyInterval (TEdit) - the edit box containing the number of seconds for
   auto-notify.
OKBtn, CancelBtn (TButton) - the OK and Cancel buttons.

About box (TAboutForm)
----------------------

VersionLabel (TLabel) - a label containing the ViRC version.
OKBtn (TButton) - the OK button.

DCC list window (TDCCListForm)
------------------------------

DCCList (TListBox) - a list box containing all the active DCC requests.
   however, it's an owner-draw control with no strings in its Items property,
   so it isn't very scriptable.
AcceptBtn (TButton) - the button to accept the currently selected request.
CloseBtn (TButton) - the button to abort the currently selected request.
DCCListPopup (TPopupMenu) - the popup menu for the list box.

Script log form (TScriptLogForm)
--------------------------------

LogOutput (TMonkeySex) - the output pane.
LogPopup (TPopupMenu) - the right-click menu.

Modifications to OVS
====================

Methods added to TStrings
-------------------------

  LoadFromEvent <eventname>
    Fills the string list with the code of the named event.
  SaveToEvent <eventname>
    Creates or replaces an event with the given name, using the code from the
    string list.
  GetEventList
    Fills the string list with the names of all defined events.
  LoadFromMenuTree <treename>
    Fills the string list with the named menu tree, in the same format as
    described earlier.
  SaveToMenuTree <treename>
    Replaces the named menu tree using the description from the string list.
  GetMenuTreeList
    Fills the string list with the names of all available menu trees.
  LoadFromMenuItem <itemname> on <treename>
    Fills the string list with the code of the named menu item.
  SaveToMenuItem <itemname> on <treename>
    Replaces the named menu item using the code from the string list.
  GetMenuItemList <treename>
    Fills the string list with the names of all menu items on the named tree,
    in seemingly random order.

New TTabbedForm class
---------------------

This is the same as TForm, but it creates a button on ViRC's tab bar. The
icon set with the form's Icon property is shown on the button.

Property:
  TabCaption (string)
    The text that appears on the button.
    
New TMonkeySex class
--------------------

This is the text scroller used on server/channel/query/DCC chat forms. (Blame
Gnowknaym for the name.)

Properties:
  Align, Font, ParentFont, PopupMenu - standard.
  Background (TColor)
    The default background color.
  BGBitmap (TBitmap)
    The background image.
  BGBitmapEnabled (boolean)
    If true, the BGBitmap will be used; otherwise, the background color will
    be used.
  BufferSize (integer)
    The number of scrollback lines to keep in memory.
  Hyperlink (TColor)
    The color to display hyperlinks in. (\Lfoo\L)
  ScriptLink (TColor)
    The color to display script links in. (\Scmd:foo\S)
  Logging (boolean)
    If true, the OnLogging event will be called for each line added.

Methods:
  Clear
    Erases all lines in the control.
  PageDown
    Scrolls down one page.
  PageUp
    Scrolls up one page.

Events:
  OnClick, OnDblClick - standard.
  OnCopyText
    Called when the user selects some text and releases the mouse button. The
    text is in $Text.
  OnHyperlink
    Called when the user double-clicks a hyperlink. The link text is in $Text.
  OnScriptLink
    Called when the user activates a script link. The associated command is in
    $Command, the visible text is in $Text, the mouse button is in $Button,
    the shift state is in $Shift, the client coordinates of the click are in
    $X and $Y, and the screen coordinates are $ScreenX and $ScreenY.
  OnLogging
    Called when a new line is added and logging is enabled. The text is in
    $Text.

New TSockets class for TCP connections
--------------------------------------

Create a TSockets object with the syntax $New(TSockets). These socket controls
will automatically use the specified SOCKS proxy settings for outgoing
connections, but listening for connections will not be possible over SOCKS.

If a socket error occurs and no OnErrorOccurred event handler is set, ViRC
will stop. If you don't plan to handle errors, you should at least set a
dummy event handler:  @p $socket.OnErrorOccurred = Nop
('Nop' should not be confused with 'Nil', which unsets the event handler,
causing the error to go uncaught.)

Properties:
  IPAddr (string)
    The IP address or hostname to connect to.
  Port (string)
    The port number or name to connect to.
  LocalIPAddr (string)
    The IP address of the local host. May not be accurate if the host has
    more than one address. Read-only.
  RemoteIPAddr (string)
    The IP address of the host on the other end of the connection. If the
    connection is running through SOCKS, this will be the address of the
    proxy server. Read-only.
  SocketNumber (integer)
    The number of the currently active connection.
  MasterSocket (integer)
    The number of the listening connection, if this socket object is listening.
  Text (string)
    Reading this property receives data from the socket (and removes the data
    from the socket's input buffer); writing it sends data to the socket. This
    should only be read from an OnDataAvailable event handler.
  State (enumeration)
    The socket's level of activity: sockDisconnected, sockDNS (looking up a
    hostname), sockConnecting (waiting to connect to a host), sockConnected, or
    sockRequestedSocks (waiting for a response from the proxy server).

Methods:
  SConnect
    Attempts to connect to the host in IPAddr and the port in Port. The
    OnSessionConnected or OnErrorOccurred event will be called when the socket
    connects or fails to connect.
  SListen
    Begins listening for connections on the socket using the port number in
    Port.
  SListenOnFreePort()
    Picks an unused port number, begins listening for connections on that port,
    then returns the port number.
  SListenRange(<lowport> <highport>)
    Attempts to listen on a free port between <lowport> and <highport>.
    Returns the port number if successful, or 0 if unsuccessful.
  SCancelListen
    Cancels listening.
  SAccept()
    Accepts the connection and returns its connection number. Use this in an
    OnSessionAvailable event.
  SClose
    Closes the connection. Does not call the OnSessionClosed event.
  Send <text>
    Sends the text without a newline.
  SendCRLF <text>
    Sends the text, followed by a carriage return and linefeed.
  SetActiveConnection(<num>)
    Sets the active connection (just like setting the SocketNumber property)
    and returns the number of the previously active connection.

Events:
  OnStateChanged
    Called when the socket's State property changes. The new state is in the
    $State variable.
  OnDataAvailable
    Called when data is available for reading. Read the Text property to get
    the data. The socket number is in $Socket.
  OnDataNeeded
    Called when the socket is ready to write, either just after connecting or
    after a previous write failed. Set the Text property or use the Send or
    SendCRLF methods to write data. The socket number is in $Socket.
  OnSessionAvailable
    Called when a client is trying to connect to a listening socket. Call
    SAccept to accept the connection.
  OnSessionClosed
    Called when the remote host has closed the connection. Call SClose here
    to close down your side of the connection. The socket number is in $Socket.
  OnSessionConnected
    Called when an outgoing connection succeeds. The socket number is in
    $Socket.
  OnErrorOccurred
    Called when a socket error occurs. If this is not handled, the application
    will be stopped. The socket number is in $Socket, the error number is in
    $Error, and the error message is in $Msg.

TSockets example
----------------

Outgoing connections:
  // create socket
  @ $socket = $new(TSockets)
  // set up events
  @p $socket.OnSessionConnected = SMTP_SESSIONCONNECTED
  @p $socket.OnErrorOccurred = SMTP_ERROROCCURRED
  // we'll use mail.myisp.com for SMTP (port 25)
  @p $socket.IPAddr = mail.myisp.com
  @p $socket.Port = 25
  // connect
  $socket.SConnect
  
  // OnSessionConnected event handler
  Alias SMTP_SESSIONCONNECTED
    // send a message
    // get email addresses
    @l $to = $?="Enter an address to send mail to:"
    @l $from = $?="Enter your return address:"
    // SMTP identify to server (the socket is in $Sender)
    $Sender.SendCRLF HELO vircmail
    // SMTP message headers
    $Sender.SendCRLF MAIL FROM:$from
    $Sender.SendCRLF RCPT TO:$to
    // body
    $Sender.SendCRLF DATA
    $Sender.SendCRLF From: $from
    $Sender.SendCRLF To: $to
    $Sender.SendCRLF Subject: Mail sent from ViRC
    $Sender.SendCRLF
    $Sender.SendCRLF This message was brought to you by TSockets.
    // end message
    $Sender.SendCRLF .
    $Sender.SClose
  EndAlias
  
  // OnErrorOccurred event handler
  Alias SMTP_ERROROCCURRED
    // just show a message box
    MessageBox Socket error $Error occurred ($Msg)
  EndAlias

Multiple Interpreters
=====================

ViRC has a script interpreter for each server, and a global script interpreter
for action that isn't associated with a server. The global interpreter runs
ViRC.lib, <OnStart>, <OnClose>, main menu items, and DCC chat commands/events/
popups. The server interpreters run code for any command, event, or popup
that occurs in the server, channel, or query windows. OVS event handlers are
run by the interpreter that set them.

Window names and OVS object handles are only available to the interpreter
they belong to (although DCC chat window names can be used everywhere). This
means that if you create objects that need to be used from more than one
server, it's best to create them on the global interpreter.


Using BCONV
===========

The included BCONV utility can be used to easily create forms in OVS. BCONV
translates form (.dfm) files created with Delphi into script files that can
be used without much modification.

BCONV can be used two ways. The first way reads a form from a binary DFM
file:

  C:\ViRC> bconv myform.dfm myform.vsc

The second way extracts a form resource from any program compiled with
Delphi:

  C:\ViRC> bconv ViRC.exe/TCONFIGFORM configform.vsc

The part before the slash is the EXE or DLL filename; the part after is the
resource name. To get a list of resources, use a question mark for the name:

  C:\ViRC> bconv ViRC.exe/?

Note that BCONV is not perfect, and many forms cannot be converted to OVS
that will work in ViRC. For example, BCONV doesn't make valid code from
forms that have controls with collections (like status bars), doesn't put a
dollar sign in front of the component name for properties that contain
objects, and ignores properties that contain binary data (like icons). Always
read over the output to ensure that it is valid.